Gitea MCP Tool

# AI Claude 开发规范 本文档为 AI 助手（Claude）提供项目开发和发布的标准操作流程。 ## 项目概述 - **项目名称**: gitea-mcp-tool - **npm 包名**: gitea-mcp-tool - **主仓库**: Gitea (gitea.ktyun.cc:Kysion/entai-gitea-mcp) - **镜像仓库**: GitHub (github.com:SupenBysz/gitea-mcp-tool) - **npm 发布**: 通过 GitHub Actions 自动化 ## 发布工作流 ``` 本地开发 → Gitea (主仓库) → GitHub (镜像) → npmjs (自动发布) ``` ## 标准发布流程 ### 1. 版本更新 根据更新类型选择版本号： ```bash # 修复 bug (1.5.3 → 1.5.4) npm version patch # 新功能 (1.5.3 → 1.6.0) npm version minor # 重大变更 (1.5.3 → 2.0.0) npm version major ``` ### 2. 构建项目 ```bash npm run build ``` ### 3. 提交更改 ```bash git add . git commit -m "chore: release vX.X.X" ``` ### 4. 同步到两个仓库 **推荐方式**：使用同步脚本 ```bash ./sync-to-github.sh ``` **手动方式**： ```bash # 推送到 Gitea git push origin main --tags # 推送到 GitHub git push github main --tags ``` ### 5. 创建 Gitea Release（可选） 如果需要在 Gitea 上创建 Release： ```bash # 使用 keactl 创建 keactl release create --tag vX.X.X --name "vX.X.X" --body "发布说明" # 或使用 API curl -X POST \ -H "Authorization: token ${GITEA_API_TOKEN}" \ -H "Content-Type: application/json" \ "https://gitea.ktyun.cc/api/v1/repos/Kysion/entai-gitea-mcp/releases" \ -d '{ "tag_name": "vX.X.X", "name": "vX.X.X", "body": "发布说明" }' ``` ### 6. 验证自动发布 推送 tag 到 GitHub 后，自动触发： 1. ✅ GitHub Actions 构建 2. ✅ 发布到 npmjs 3. ✅ 创建 GitHub Release 查看状态：https://github.com/SupenBysz/gitea-mcp-tool/actions ## 完整发布清单 在发布新版本前，请确认： - [ ] 代码已经过测试 - [ ] 更新 `package.json` 版本号（`npm version` 会自动完成） - [ ] 更新 `README.md` 版本说明（如有必要） - [ ] 运行 `npm run build` 构建成功 - [ ] 提交所有更改 - [ ] 创建版本标签 - [ ] 推送到 Gitea：`git push origin main --tags` - [ ] 推送到 GitHub：`git push github main --tags` - [ ] 验证 GitHub Actions 发布成功 - [ ] 验证 npm 包已更新：`npm view gitea-mcp-tool` ## GitHub Actions 配置 ### 必需的 Secret 在 GitHub 仓库设置中配置： - **NPM_TOKEN**: npm 访问令牌 - 位置：https://github.com/SupenBysz/gitea-mcp-tool/settings/secrets/actions - 值：你的 npm access token（从 npmjs.com 获取） - 获取方式：`npm login && npm token create --read-only=false` ### 工作流文件 `.github/workflows/npm-publish.yml` - 触发：推送 `v*` 格式的 tag - 步骤：checkout → setup Node.js → install → build → publish - 自动创建 GitHub Release ## 故障排查 ### 发布失败 1. **检查 GitHub Actions 日志** - https://github.com/SupenBysz/gitea-mcp-tool/actions - 查看失败的步骤和错误信息 2. **常见问题** - NPM_TOKEN 过期或未配置 - 版本号已存在（需要增加版本） - 构建失败（检查本地是否能成功构建） 3. **回滚操作** ```bash # 删除本地标签 git tag -d vX.X.X # 删除远程标签 git push origin :refs/tags/vX.X.X git push github :refs/tags/vX.X.X ``` ### 同步问题 如果两个仓库不同步： ```bash # 查看远程仓库状态 git remote -v # 强制同步到 GitHub git push github main --tags --force # 查看所有标签 git tag # 单独推送某个标签 git push github vX.X.X ``` ## 远程仓库配置 项目配置了两个远程仓库： ```bash # Gitea (origin) - 主仓库 origin gitea.ktyun.cc:Kysion/entai-gitea-mcp.git (fetch) origin gitea.ktyun.cc:Kysion/entai-gitea-mcp.git (push) # GitHub (github) - 镜像仓库 github git@github.com:SupenBysz/gitea-mcp-tool.git (fetch) github git@github.com:SupenBysz/gitea-mcp-tool.git (push) ``` ## 维护命令 ```bash # 查看当前版本 npm view gitea-mcp-tool version # 查看包信息 npm view gitea-mcp-tool # 查看所有标签 git tag # 查看最近的提交 git log --oneline -10 # 查看远程仓库 git remote -v # 测试本地安装 npm link gitea-mcp --help ``` ## 开发提示 ### 本地测试 ```bash # 监听模式开发 npm run dev # 构建 npm run build # 本地全局安装测试 npm link ``` ### 代码规范 ```bash # 检查代码风格 npm run lint # 自动修复 npm run lint:fix # 类型检查 npm run typecheck ``` ## 相关链接 - **Gitea 仓库**: https://gitea.ktyun.cc/Kysion/entai-gitea-mcp - **GitHub 仓库**: https://github.com/SupenBysz/gitea-mcp-tool - **npm 包**: https://www.npmjs.com/package/gitea-mcp-tool - **GitHub Actions**: https://github.com/SupenBysz/gitea-mcp-tool/actions ## 注意事项 1. **不要手动发布到 npm** - 所有 npm 发布都应通过 GitHub Actions 自动完成 - 避免因手动操作导致的版本不一致 2. **标签命名规范** - 必须使用 `v` 前缀：`v1.5.3` - 遵循语义化版本：`vMAJOR.MINOR.PATCH` 3. **同步顺序** - 始终先推送到 Gitea（主仓库） - 再推送到 GitHub（触发自动发布） 4. **版本一致性** - package.json 版本号 - git tag 版本号 - README.md 版本说明 - 三者必须保持一致 5. **构建验证** - 推送前必须确保本地构建成功 - 检查 `dist/` 目录是否正确生成 ## 快速参考 ```bash # 完整发布流程（一键） npm version patch && \ npm run build && \ git add . && \ git commit -m "chore: release v$(node -p 'require("./package.json").version')" && \ ./sync-to-github.sh # 查看发布状态 open https://github.com/SupenBysz/gitea-mcp-tool/actions # 验证 npm 发布 npm view gitea-mcp-tool version ```